# Bootloaders & Hardware Boot Manual This document provides a comprehensive technical manual detailing the bootloader generation, partitioning schemes, firmware integration, and kernel boot chains across all 12 supported architecture targets in **Void-Builder**. --- ## 1. Boot Architecture Overview Matrix | Architecture Target | Primary Bootloader | Partitioning Scheme | Firmware / Boot Files | Kernel Image Name | | :--- | :--- | :--- | :--- | :--- | | `x86_64` | Hybrid SYSLINUX (BIOS) + GRUB2 (UEFI) | ISO 9660 / El Torito | `isolinux.bin`, `isohdpfx.bin`, `efiboot.img` | `vmlinuz` | | `x86_64-musl` | Hybrid SYSLINUX (BIOS) + GRUB2 (UEFI) | ISO 9660 / El Torito | `isolinux.bin`, `isohdpfx.bin`, `efiboot.img` | `vmlinuz` | | `i686` | Hybrid SYSLINUX (BIOS) + GRUB2 (UEFI) | ISO 9660 / El Torito | `isolinux.bin`, `isohdpfx.bin`, `efiboot.img` | `vmlinuz` | | `aarch64` | GRUB2 ARM64 EFI | ISO 9660 / UEFI FAT | `bootaa64.efi`, `efiboot.img` | `vmlinux` | | `aarch64-musl` | GRUB2 ARM64 EFI | ISO 9660 / UEFI FAT | `bootaa64.efi`, `efiboot.img` | `vmlinux` | | `armv7l` | GRUB ARM EFI / U-Boot | ISO 9660 / FAT | `bootarm.efi`, `efiboot.img` | `vmlinux` | | `armv7l-musl` | GRUB ARM EFI / U-Boot | ISO 9660 / FAT | `bootarm.efi`, `efiboot.img` | `vmlinux` | | `rpi-aarch64` | Raspberry Pi Native Firmware | MBR (VFAT + EXT4) | `bootcode.bin`, `start.elf`, `cmdline.txt` | `kernel8.img` | | `rpi-armv7l` | Raspberry Pi Native Firmware | MBR (VFAT + EXT4) | `bootcode.bin`, `start.elf`, `cmdline.txt` | `kernel7.img` | | `rpi-armv6l` | Raspberry Pi Native Firmware | MBR (VFAT + EXT4) | `bootcode.bin`, `start.elf`, `cmdline.txt` | `kernel.img` | | `pinebookpro` | Rockchip RK3399 U-Boot | GPT (VFAT + EXT4) | `idbloader.img`, `u-boot.itb` | `vmlinuz` | | `asahi` | GRUB2 ARM64 EFI | MBR/GPT (VFAT + EXT4) | `bootaa64.efi`, `m1n1` stage | `vmlinuz-asahi` | --- ## 2. PC Hybrid ISO Boot Mechanism (x86_64 / i686) PC live ISO images generated by `VoidEngine` support dual boot capability: booting under legacy BIOS systems and 32/64-bit UEFI systems. ### A. BIOS Legacy Boot (SYSLINUX) - **Files Location**: `boot/isolinux/` inside the ISO image. - **Boot Entry Binary**: `isolinux.bin` - **MBR Sector Embedding**: `VoidEngine` extracts `isohdpfx.bin` from `usr/lib/syslinux/isohdpfx.bin` and passes it to `xorriso` via `-isohybrid-mbr`. This enables booting when the ISO is written directly to a USB drive with `dd`. - **Menu System**: Uses `vesamenu.c32` to render a 800x600 graphical menu using the background splash PNG (`configs/assets/data/splash.png`). #### Generated `isolinux.cfg` Template: ```text DEFAULT vesamenu.c32 PROMPT 0 TIMEOUT 100 MENU TITLE Pepvoid Live ISO MENU BACKGROUND /boot/isolinux/splash.png LABEL void_live MENU LABEL Boot Void Linux Live (x86_64) LINUX /boot/vmlinuz INITRD /boot/initrd APPEND quiet splash live.user=live live.autologin rd.live.overlay.overlayfs=1 ``` ### B. UEFI Boot (GRUB2 EFI) - **Boot Image**: `boot/grub/efiboot.img` (FAT16 image embedded inside ISO). - **EFI Binary**: `EFI/BOOT/BOOTX64.EFI` (64-bit) or `EFI/BOOT/BOOTIA32.EFI` (32-bit). - **`xorriso` Integration**: Linked into the ISO header via: ```bash -eltorito-alt-boot \ -e boot/grub/efiboot.img \ -no-emul-boot \ -isohybrid-gpt-basdat \ -isohybrid-apm-hfsplus ``` --- ### C. PC virtual disk images (VDI, QCOW2, VMDK, IMG/RAW) These images use UEFI GRUB on a FAT ESP and keep the kernel/initramfs on the root partition labelled `void_root`. The standalone EFI loader must load `part_gpt` (and `part_msdos` for MBR targets) before searching for that partition. Merely including the module files in the standalone memdisk does not ensure partition drivers are loaded. Without them, GRUB can list `(hd0)` but no partitions, then report `no such device: void_root` followed by `file /boot/vmlinuz not found` even when the kernel is present. The disk builder explicitly loads the partition/filesystem modules, selects a matching nonempty kernel/initramfs pair, and uses their filenames in both the embedded configuration and `/boot/grub/grub.cfg`. It also creates `/boot/efi` before exporting the root filesystem so the ESP mount in `/etc/fstab` succeeds. Missing boot files abort the build before packaging. The disk menu defaults to the newest complete kernel/initramfs pair and remains visible for five seconds. It offers normal boot, safe graphics (`nomodeset`), and an **Advanced options for Void Linux** submenu containing normal and recovery entries for each complete installed kernel. Recovery uses Void/runit's `single` mode. Incomplete kernel/initramfs pairs are omitted. UEFI firmware settings appear only when supported by the firmware; restart and shutdown entries are also available. These entries apply to disk images; the live ISO menu is generated separately. ## 3. Raspberry Pi Single-Board Computers (`rpi-*`) Raspberry Pi computers do not use traditional BIOS or UEFI. Instead, the VideoCore GPU boots first, reads files from the primary VFAT partition, and loads the ARM Linux kernel. ### Disk Partition Map (MBR) - **Sector 2048 to +256MiB**: Partition 1 (Type `0x0c` FAT16, bootable). Mounted as `/boot`. - **Sector +256MiB to End**: Partition 2 (Type `0x83` Linux EXT4). Mounted as `/`. ### Critical `/boot` Firmware Files 1. `bootcode.bin`: GPU bootloader stage. 2. `start.elf`: VideoCore GPU firmware binary. 3. `fixup.dat`: GPU memory allocation configuration file. 4. `config.txt`: Raspberry Pi hardware configuration options. 5. `cmdline.txt`: One-line kernel parameters. #### Generated `cmdline.txt` Format: ```text root=PARTUUID=a1b2c3d4-02 rw rootwait console=ttyAMA0,115200 console=tty1 quiet splash ``` --- ## 4. Pinebook Pro Laptop (`pinebookpro`) The Pinebook Pro is powered by the Rockchip RK3399 ARM64 SoC. It boots using U-Boot written to raw disk sectors before the first partition. ### GPT Sector Map - **Sectors 0 to 63**: GPT Header & Partition Table. - **Sector 64 (32 KiB Offset)**: `idbloader.img` written via `dd if=idbloader.img of=/dev/sdX bs=512 seek=64 conv=notrunc,fsync`. - **Sector 16384 (8 MiB Offset)**: `u-boot.itb` written via `dd if=u-boot.itb of=/dev/sdX bs=512 seek=16384 conv=notrunc,fsync`. - **Partition 1 (512MiB, FAT16)**: `/boot` partition containing Linux kernel and initramfs. - **Partition 2 (Remainder, EXT4)**: Root filesystem. --- ## 5. Apple Silicon Macs (`asahi`) Apple Silicon Macs (M1/M2/M3 chips) boot via Apple's proprietary boot chain (`m1n1` stage 1 -> U-Boot stage 2 -> GRUB2 EFI stage 3). ### Asahi Boot Sequence 1. `PlatformEngine` detects `asahi` target architecture. 2. Partition 1 (256MiB FAT16) is formatted for EFI. 3. GRUB ARM64 EFI is installed inside chroot: ```bash grub-install --target=arm64-efi --efi-directory=/boot --removable /dev/loopX ``` 4. Executes `xbps-reconfigure -f linux-asahi` to generate Apple Silicon device trees (`.dtb` files) and kernel modules.